There are a couple of tools that allow to produce appealing API documentation with Javadoc.
UMLGraph is one of them.
Using UMLGraph
The Doclet allows to render UML diagrams automatically in Javadoc reports like this:
This gives a good overview over the relationships of the highlighted class. It also allows navigating to another class by clicking on it.
Maven Configuration
To integrate this in your Maven build, use this configuration for the Maven Javadoc Plugin:
<plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-javadoc-plugin</artifactId> <configuration> ... <doclet>org.umlgraph.doclet.UmlGraphDoc</doclet> <docletArtifact> <groupId>org.umlgraph</groupId> <artifactId>UmlGraph</artifactId> <version>5.6</version> </docletArtifact> <additionalparam> -inferrel -inferdep -quiet -hide java.* -collpackages java.util.* -qualify -postfixpackage -nodefontsize 9 -nodefontpackagesize 7 </additionalparam> ... </configuration> </plugin>
This snippet shows only the relevant part for the integration of the doclet.
Limitations
Since the UML diagram is drawn automatically, you have no control over the layout.
This may result in a diagram not worth showing:
Or you may encounter a diagram that simply tells to much:
Despite this minor limitations we usually include the automatically generated diagrams in our Javadoc reports. If you want to add manually crafted diagrams, please have a look at our article Using PlantUML (this can probably also be done with UMLGraph).
References and other Resources
- taglets.sourceforge.net - for more information on this library.
- Using PlantUML - shows how to use PlantUML from within Javadoc.
- Appealing API Documentation with Taglets - short article on how to use taglets in Javadoc.
- Doclet - more information about doclets as part of Javadoc.
There are a couple of tools that allow to produce appealing API documentation with Javadoc.
The taglets library is one of them.
Using taglets
The taglets library has defined a couple of visually attractive taglets that allow to highlight important information within an API or even render Java source code (e.g. for example usage scenarios). Here is an example from the API documentation of one of our projects (it shows an element of an annotation):
Maven Configuration
To integrate this in your Maven build, use this configuration for the Maven Javadoc Plugin:
<plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-javadoc-plugin</artifactId> <configuration> ... <taglets> <taglet> <tagletClass>net.sourceforge.taglets.Taglets</tagletClass> <tagletArtifact> <groupId>net.sourceforge.taglets</groupId> <artifactId>taglets</artifactId> <version>2.0.3</version> </tagletArtifact> </taglet> </taglets> ... </configuration> </plugin>
This snippet shows only the relevant part for the integration of the taglets library. The artifact can be found on our Nexus server.
References and other Resources
- taglets.sourceforge.net - for more information on this library.
- Using PlantUML - shows how to use PlantUML from within Javadoc.
- Appealing API Documentation with UMLGraph - short article on how to use UMLGraph in Javadoc to automatically generate UML class diagrams.
- Taglet - more information about taglets as part of Javadoc.
The library smartics-commons for Java has been released with version 0.4.0.
A new helper class called Arg
to check arguments has been introduced. The old class Arguments
has been marked as deprecated.
We also made information relevant to developers to decide about using this library more easily accessible from the project's homepage.